home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / tex / bfmt139.zip / BFMT139.DOC < prev    next >
Text File  |  1993-04-28  |  13KB  |  506 lines
  1. BFMT.EXE    ----------------------------------------------------
  2.  
  3. This program is free and you are welcome to use it at your own
  4. risk.  If you pass it on please give this accompanying document as
  5. well. 
  6.  
  7. Also if you do use it, or a modified form of it, please acknowledge 
  8. the original author: Brendan Babb.
  9.  
  10. If you modify, improve upon, or have suggestions for this program
  11. Please email me (Brendan@micro.uct.ac.za).
  12.  
  13. -----------------------------------------------------------------
  14.  
  15.  
  16.  
  17. BFMT.EXE - text formatting        
  18.  
  19. What can bfmt do ?
  20.     * align text 
  21.     * format paragraphs      - centre
  22.                 - left
  23.                 - right
  24.                 - justified
  25.                 - unchanged
  26.     * inherit whitespace or specify whitespace
  27.     * embedded formatting options in the text
  28.  
  29. What does it work on?
  30.     * bfmt is really designed for use with vi like editors
  31.       such as elvis
  32.     * you can bfmt any text file from the command line 
  33.       by 'TYPE {filename} | BFMT [options] [>{filename}]'
  34.       or 'BFMT [options] <{input} >{output}'
  35.  
  36. /-----------------------------------------------------------------
  37. How do I use BFMT ?
  38.  
  39.     You can use the program from either the command line or from
  40.     within an editor like elvis.  From the command line if you run
  41.     'BFMT' input will be taken from the keyboard and outputed to
  42.     the screen.  This isnt particularly useful but with
  43.     redirection you can save text entered and/or input from a
  44.     file.
  45.  
  46.            For example 'BFMT >output.txt' will take whatever you type as
  47.               input and save the output to the file output.txt.  It will
  48.              save whatever text entered (until you type ^Z) in formatted
  49.                 form in the file output.txt.  Similarly 'BFMT <input.txt
  50.                >output.txt' will take text from input.txt and save it in
  51.           output.txt. Alternatively 'TYPE input.txt | >>output.txt' will
  52.                take input.txt as input and append the output to the file
  53.                                                              output.txt.
  54.  
  55.              If you use vi-like editors (elvis) you can map various
  56.           options to different keys.  I've mapped '!}BFMT -fl' to Alt-L
  57.             and '!}BFMT -fj' to Alt-J etc.  These mappings format the
  58.              text from the cursor's line through till the end of the
  59.              current paragraph.  See the examples below for what the
  60.                   various options on formatting actually are. 
  61.  
  62.     A few  notes: bfmt thinks  in words,  lines  and paragraphs.  So
  63.     separate paragraphs  with blank lines, or lines  beginning  with
  64.     paragraph markers.    Otherwise specify the option to treat each
  65.     line  as a separate paragraph.  Bfmt  works by  collecting    as
  66.     many words  as it can before it reaches a  new paragraph.  These
  67.     words  and the  last input    line   are  passed  to  formatting
  68.     functions.   If a line beginning with  a paragraph  marker    is
  69.     found, then  that line is saved to    a parameter buffer.   This
  70.     buffer is dealt  with after formatting  and output, so that only
  71.     subsequent paragraphs are affected by it. 
  72.  
  73.     
  74.  
  75. /-----------------------------------------------------------------
  76. Option Summary
  77.  
  78. -?        display options and defaults
  79. -a{0|1}        all lines treated as paragraphs or not    
  80. -f{a|c|l|r|j|u}    format type
  81.         note that -fa indents c/c++ text for you
  82. -h        display options and defaults
  83. -i{0|1}        inherit whitespace or not
  84. -m{number}    minimum number of words to format in justify
  85. -s{number}    amount of whitespace when -i0
  86. -t{0|1}        to follow text embedded options 
  87.         the following options are recognised
  88.         -a, -w, -f, -i, -k, -s, -h (current defaults), -w
  89. -v        display version
  90. -w{number}    right margin
  91. -{{list}    list of paragraph identifiers (for recognizing 
  92.         text embedded options)        
  93. -({list}    list of sentence markers (gets a forced double space
  94.         afterwards)
  95. -u        save the options previously listed on command line 
  96.         as the defaults.
  97. ?        display options and defaults
  98.  
  99.  
  100.  
  101.  
  102. /------------------- EXAMPLES -----------------
  103.  
  104.      The following  are  examples of bfmt in action.  All the examples
  105.      use the text  below as their  input.  I ran  bfmt from  elvis 1.7
  106.      by using  the  following command 
  107.  
  108.          :r !bfmt <sample [options] 
  109.  
  110.      This looks rather messy, but the output looks neater!
  111.  
  112.  
  113. -------> begin sample text
  114. // ------------- Sample text. ---------------
  115.         #define
  116.     // practice c
  117. main () {
  118.     sample com1
  119. com2
  120.     for (int i = ; ; ) {
  121. do this
  122.     do that
  123. do nothing
  124.     }
  125. wait around and make mistakes
  126.     }
  127.  
  128. // practice text
  129.         This is sample test.
  130.             This is sample test.
  131.         This is sample test.
  132.     line     two
  133.     line         three
  134.     And more sample text.
  135.     .-w50 -fr 
  136.     with still even more text to use ansd reuse 
  137. blah blah blah blah hi world bye world
  138.  
  139.     Last line.
  140. // -------------------------------------- ----------------
  141. ---------> end sample text
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152. Example 1 : BFMT 
  153.  
  154.      In this example, the defaults as supplied are used.  All text
  155.      is assumed to be paragraphs.  As many words as possible are
  156.      crammed into each line.  Note that the embedded commands are
  157.      obeyed to produce a right format paragraph.
  158.  
  159. --------->    begin     output
  160. // ------------- Sample text. ---------------
  161.         #define
  162. // practice c
  163. main () { sample com1 com2 for (int i = ; ; ) { do this do that do
  164. nothing } wait around and make mistakes }
  165.  
  166. // practice text
  167.         This is sample test. This is sample test. This is
  168.         sample test. line two line three And more sample text.
  169. .-w50 -fr 
  170.              with still even more text to use ansd
  171.             reuse blah blah blah blah hi world bye
  172.                                              world
  173.  
  174.                                         Last line.
  175. // -------------------------------------- ----------------
  176.         --------->    end     output
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187. Example 2 : BFMT -t0
  188.  
  189.      In this example bfmt is told not obey options embedded in the
  190.      text itself (ie -w50 -fr).  The last paragraph is no longer
  191.      right formatted.
  192.  
  193. ---------->    begin     output
  194. // ------------- Sample text. ---------------
  195.         #define
  196. // practice c
  197. main () { sample com1 com2 for (int i = ; ; ) { do this do that do
  198. nothing } wait around and make mistakes }
  199.  
  200. // practice text
  201.         This is sample test. This is sample test. This is
  202.         sample test. line two line three And more sample text.
  203. .-w50 -fr 
  204.     with still even more text to use ansd reuse blah blah blah
  205.     blah hi world bye world
  206.  
  207.     Last line.
  208. // -------------------------------------- ----------------
  209. --------->    end     output
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220. Example 3 :  BFMT -i0
  221.  
  222.      Here, BFMT is told not to inherit whitespace, but to use the
  223.      default -s{} setting (8).  Notice that the lines beginning with /
  224.      are still aligned to the very left.  This is because BFMT has
  225.      been told ( -{ ) to see / as a paragraph marker. 
  226.  
  227. --------->    begin     output
  228. // ------------- Sample text. ---------------
  229.         #define
  230. // practice c
  231.         main () { sample com1 com2 for (int i = ; ; ) { do this do
  232.         that do nothing } wait around and make mistakes }
  233.  
  234. // practice text
  235.         This is sample test. This is sample test. This is sample test.
  236.         line two line three And more sample text.
  237. .-w50 -fr 
  238.              with still even more text to use ansd
  239.             reuse blah blah blah blah hi world bye
  240.                                              world
  241.  
  242.                                         Last line.
  243. // -------------------------------------- ----------------
  244. --------->    end     output
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255. Example 4.  : BFMT -a1
  256.  
  257.     Each line is assumed to be a separate paragraph here.  The
  258.     affect is that any lines that are too long will be chopped
  259.     into two lines and white space within a line is reduced to
  260.         single spaces.
  261.  
  262. --------->    begin     output
  263. // ------------- Sample text. ---------------
  264.         #define
  265. // practice c
  266. main () {
  267.     sample com1
  268. com2
  269.     for (int i = ; ; ) {
  270. do this
  271.     do that
  272. do nothing
  273.     }
  274. wait around and make mistakes
  275.     }
  276.  
  277. // practice text
  278.         This is sample test.
  279.             This is sample test.
  280.         This is sample test.
  281.     line two
  282.     line three
  283.     And more sample text.
  284. .-w50 -fr 
  285.              wi